Skip to main content

Flutter SDK 插件

Flutter SDK 插件提供了无埋点 SDK 和埋点 SDK 两个版本,在使用 Flutter 无埋点 SDK 前,需要按照 Flutter Aspect 集成 才能使无埋点功能生效。


环境配置

info

Growingio Flutter SDK 插件集成

添加依赖

以工程flutter_app为例,在pubspec.yaml文件中添加依赖。

dependencies:
growingio_autotracker_flutter_plugin: '2.2.0'

然后执行 flutter pub get 指令安装插件。

点击查看Growingio Flutter 插件和 SDK 版本的依赖关系
Flutter 插件版本Android SDK 版本范围iOS SDK 版本范围HarmonyOS SDK 版本范围
= v1.0.0>= v3.4.7>= v3.4.8
= v1.1.0>= v3.5.0>= v3.5.0
= v1.1.3>= v3.5.0>= v3.5.0
= v2.1.0>= v3.5.0>= v3.5.0
= v2.1.2>= v3.5.0>= v3.8.3
= v2.1.3>= v3.5.0>= v3.8.3
= v2.2.0>= v3.5.03.9.x(>= v3.9.2)2.9.x

添加 Android 依赖

添加 maven 仓库

在 project 级别的 build.gradle 文件中添加 Maven 仓库

buildscript {
repositories {
// 添加maven仓库
mavenCentral()
//如果使用 SNAPSHOT 版本,则需要使用如下该仓库。
maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots/" }
}
}

allprojects {
repositories {
// 添加maven仓库
mavenCentral()
//如果使用 SNAPSHOT 版本,则需要使用如下该仓库。
maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots/" }
}
}
添加依赖

在 app 级别的 build.gradle 文件中添加代码依赖

apply plugin: 'com.android.application'

dependencies {
implementation 'com.growingio.android:autotracker-cdp:3.5.1'
implementation 'com.growingio.android:flutter:3.5.1'
}
添加插件(集成无埋点需要)

在 project 级别的 build.gradle 文件中添加插件路径

buildscript {
...

dependencies {
//GrowingIO 无埋点 SDK plugin
classpath 'com.growingio.android:autotracker-gradle-plugin:3.5.0'
}
}

在 app 级别的 build.gradle 文件中添加 com.growingio.android.autotracker 插件

apply plugin: 'com.android.application'
//添加 GrowingIO 插件
apply plugin: 'com.growingio.android.autotracker'

...
关于插件

插件最新发布版本为 Github Releases

关于如何在 Android Gradle Plugin 7 及其更高版本使用插件请参考 SDK 插件说明

iOS 集成方式说明

从 v2.2.0 起,插件同时支持 Swift Package Manager(SPM)与 CocoaPods 两种 iOS 原生依赖管理方式,均无需在 iOS 工程中手动添加 GrowingIO 原生 SDK 依赖。

Flutter 3.44 及以上(默认 SPM 模式)

添加依赖后无需任何额外操作,构建时 Flutter 会自动通过 SPM 引入插件及原生 GrowingAnalytics SDK(要求原生 SDK ≥ 3.9.2)。旧工程首次构建时 Flutter 会自动完成 SPM 集成迁移。

caution

如果 Podfile 中曾手动添加过 pod 'GrowingAnalytics-cdp/...'pod 'GrowingAnalytics/...',SPM 模式下必须删除这些行,否则 SDK 会被集成两份,链接时报 duplicate symbols。

Flutter 3.44 以下,或手动禁用了 SPM

继续通过 CocoaPods 集成,行为与旧版本完全一致,同样无需额外操作。禁用 SPM 的方式:

# pubspec.yaml
flutter:
config:
enable-swift-package-manager: false

原生 + Flutter 混合开发

CocoaPods 模式下原生代码可直接 import GrowingAutotracker;SPM 模式下插件的依赖对 app target 默认不可见,若原生代码需要直接调用 SDK API,请在 Xcode 中 File → Add Package Dependencies… → 输入 https://github.com/growingio/growingio-sdk-ios-autotracker.git(版本 3.9.2 起)→ 勾选 GrowingAutotracker_cdp(无埋点)或 GrowingTracker_cdp(埋点)产品添加到 app target。SPM 会自动与插件已依赖的同一个包去重,不会产生重复代码。

HarmonyOS 集成说明

从 v2.2.0 起,插件支持 HarmonyOS 平台,桥接 HarmonyOS 原生 SDK @growingio/analytics(CDP 模式)。

caution

HarmonyOS 平台 CDP 模式目前仅支持埋点采集,暂不支持无埋点采集(PAGE / VIEW_CLICK / VIEW_CHANGE)与圈选(服务端限制),因此无需替换 AOP snapshot;扫码数据校验(MobileDebugger)不受影响。
此外,HarmonyOS 平台暂不支持 doDeepLinkByUrl(广告归因)与初始化后动态注册组件(registerComponent)。加解密(EncoderLibraryGioModule)、Protobuf(ProtobufLibraryModule)等组件请在 startWithConfigurationmodules 参数中配置。

  1. 需使用支持 HarmonyOS 的 Flutter SDK(如 3.7.12-ohos / 3.22.x-ohos),在 Flutter 工程的 ohos 目录下构建。
  2. 原生 SDK 依赖由插件自动引入,初始化时 dataCollectionServerHost 为必传参数。
  3. 插件在注册时会自动通过 FlutterPluginBinding 获取 applicationContext 用于初始化原生 SDK,无需额外配置。
  4. 如需使用扫码数据校验(MobileDebugger),URL Scheme 配置分两部分。首先在 module.json5 中 EntryAbility 对应的 skills 添加 URL Scheme:
{
"actions": [
"ohos.want.action.viewData"
],
"uris": [
{
"scheme": "Your URL Scheme",
"host": "growingio/webservice"
}
]
}

然后在 FlutterAbility 的 onCreate/onNewWant 中将 uri 传递给 SDK:

import { FlutterAbility } from '@ohos/flutter_ohos'
import Want from '@ohos.app.ability.Want'
import AbilityConstant from '@ohos.app.ability.AbilityConstant'
import { GrowingAnalytics } from 'growingio_autotracker_flutter_plugin'

export default class EntryAbility extends FlutterAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onCreate(want, launchParam)
let uri = want?.uri
if (uri) {
GrowingAnalytics.handleOpenURL(uri)
}
}

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onNewWant(want, launchParam)
let uri = want?.uri
if (uri) {
GrowingAnalytics.handleOpenURL(uri)
}
}
}

埋点 SDK 请将上方 import 中的 growingio_autotracker_flutter_plugin 替换为 growingio_tracker_flutter_plugin

Flutter 插件初始化

GrowingIO Flutter SDK 支持在 Flutter 中初始化SDK,也同时支持在原生代码中初始化。如果需要更多的功能设置,我们更推荐您在原生端实现初始化。

原生端初始化

原生端初始化请参考各端的初始化文档:

Flutter 初始化

在 Flutter 端进行初始化,请将 SDK 的初始化代码放入 main.dartmain 中,代码示例如下:


void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
GrowingAutotracker.startWithConfiguration(
projectId: "Your ProjectId",
dataCollectionServerHost: "Your collection server host",
dataSourceId: "Your datasourceid",
urlScheme: "Yoour Url Scheme",
debugEnabled: true,
modules: {
AdvertLibraryGioModule(config: AdvertConfig()),
ProtobufLibraryModule()
},
dataCollectionEnabled: true,
idMappingEnabled: true,
cellularDataLimit: 10,
dataUploadInterval: 15,
sessionInterval: 20,
);
...
runApp(MyApp());
}

初始化配置说明

在 Flutter 初始化中会传入各式的参数,参数配置如下表所示:

配置项参数类型是否必填默认值说明版本
projectIdStringnull项目ID,每个应用对应唯一值-
urlSchemeStringnullAndroid 应用特有的URLScheme,用于外部应用拉起应用,如圈选-
dataSourceIdStringnull应用的DataSourceId,唯一值-
dataCollectionServerHostStringnull服务端部署后的 ServerHost-
channelStringnull应用的分发渠道-
debugEnabledboolfalse调试模式,会打印SDK log,抛出错误异常,在线上环境请关闭-
cellularDataLimitint10每天发送数据的流量限制,单位MB-
dataUploadIntervalint15数据发送的间隔,单位秒-
sessionIntervalint30会话后台留存时长,单位秒-
dataCollectionEnabledbooltrue是否采集数据-
modulesSet<LibraryGioModule>empty模块集成,具体请阅读下方的模块说明-

urlScheme 说明

在使用 GrowingIO SDK 的Mobile Debugger 和圈选功能时,需要外部浏览器通过扫描二维码来拉起应用。

模块配置

GrowingIO SDK 利用模块来实现SDK核心功能以外的额外功能,在 Flutter SDK 插件中,可以通过在 modules 传入模块声明来开启相应的功能。

目前 Flutter SDK 可启用的模块功能包括:

广告功能

GrowingTracker.startWithConfiguration(
//....
modules: {
AdvertLibraryGioModule(
config: AdvertConfig(readClipBoardEnable: true, /// 是否打开剪切板
deepLinkHost: "https://n.datayi.cn", /// 深度链接配置地址
asaEnabled: true, /// 仅iOS端使用
deepLinkCallback:(Map<String,String> params,int error,int time){
///监听深度链接中的地址参数
},
)),
},
//....
);

广告模块包括激活事件和深度链接,能帮助客户提供广告,活动的引导跳转和下载。

iOS 端从 v2.2.0 起,引入原生广告库的方式按集成模式二选一:

  • SPM 模式:Xcode 打开 iOS 工程 → File → Add Package Dependencies… → 输入 https://github.com/growingio/growingio-sdk-ios-autotracker.git(版本 3.9.2 起)→ 产品列表中勾选 GrowingModule_Advert 添加到 app target(SPM 会自动与插件已依赖的同一个包去重)
  • CocoaPods 模式:Podfile 中添加 pod 'GrowingAnalytics/Advert'

未引入广告库时调用 doDeepLinkByUrl 会静默降级并在控制台提示“广告模块未集成”,不会崩溃。HarmonyOS 平台暂不支持广告模块。

info

在 Flutter SDK 启动广告模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:

加密模块

GrowingTracker.startWithConfiguration(
//....
modules: {
EncoderLibraryGioModule(),
},
//....
);

加密模块用于数据网络上传数据的加密。

info

在 Flutter SDK 启动加密模块同时,Android端需要引入相应的模块代码,请参考:

Protobuf 模块

GrowingTracker.startWithConfiguration(
//....
modules: {
ProtobufLibraryModule(),
},
//....
);

Protobuf 数据模块将会使用 Google Protobuf 格式保存和上传事件数据。

info

在 Flutter SDK 启动 Protobuf 模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:

H5混合模块

GrowingTracker.startWithConfiguration(
//....
modules: {
HybridLibraryGioModule(),
},
//....
);

若使用了原生的WebView,且内嵌 H5 页面如果也需要进行数据采集(H5 页面已经集成 Web JS SDK),则可以开启该 H5混合模块。

info

在 Flutter SDK 启动H5混合模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:

API说明

GrowingAutotracker.get().setDataCollectionEnabled(true)
GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name")
GrowingAutotracker.get().cleanLoginUserId()
GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});
GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11)
GrowingAutotracker.get().cleanLocation()
GrowingAutotracker.get().getDeviceId()
GrowingAutotracker.get().trackCustomEvent(eventName: "eventName", attributes: {"age":"18"})
String? timerId =await GrowingAutotracker.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();

GrowingAutotracker.get().registerComponent(module);

1. 数据采集开关

setDataCollectionEnabled
打开或关闭数据采集

参数说明

参数参数类型说明
enabledbooleantrue打开数据采集,false关闭数据采集,默认 true

示例

GrowingAutotracker.get().setDataCollectionEnabled(true);

2. 设置登录用户ID

setLoginUserId
当用户登录之后调用,设置登录用户ID

info

支持 ID-MAPPING 需在初始化 SDK 时设置 idMappingEnabledtrue

如果您的App每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级App版本后初次访问时重新调用setLoginUserId方法

参数说明

参数参数类型说明
userIdString长度限制大于0且小于等于1000,如果大于长度1000将只截取前1000长度
userKeyString适用于ID-MAPPING,可设置 userId 的类型,可选填

示例

GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name");

3. 清除登录用户ID

cleanLoginUserId
当用户登出之后调用,清除已经设置的登录用户ID。

示例

GrowingAutotracker.get().cleanLoginUserId();

4. 设置用户的地理位置

setLocation
设置用户当前的地理位置,基于WGS-84坐标

参数说明

参数参数类型说明
latitudedouble地理坐标点纬度
longitudedouble地理坐标点经度

示例

GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11);

5. 清除用户的地理位置

cleanLocation
清除用户当前的地理位置

示例

GrowingAutotracker.get().cleanLocation();

6. 设置登录用户属性

setLoginUserAttributes
发送登录用户属性事件,用于用户信息相关分析; 在添加发送用户属性事件代码之前,需在CDP平台用户管理界面创建用户属性。

参数说明

参数参数类型说明
attributesMap<String, String>用户属性信息

示例

GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});

7. 设置埋点事件

trackCustomEvent
发送一个埋点事件;注意:在添加发送的埋点事件代码之前,需在CDP平台事件管理界面创建埋点事件以及关联事件属性;
如果事件属性需关联维度表,请在事件属性下关联维度表( CDP平台版本>= 2.1 )

参数说明

参数参数类型说明
eventNameString事件名,事件标识符
attributesMap<String, String>事件发生时所伴随的属性信息;当事件属性关联有维度表时,属性值为对应的维度表模型ID(记录ID)(可选)

示例

GrowingAutotracker.get().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});

8. 获取设备ID

getDeviceId
获取设备ID,又称为匿名用户ID,SDK 自动生成用来定义唯一设备。 如果没有初始化SDK 或者关闭采集开关可能返回值为null,且可能有IO操作。

示例

GrowingAutotracker.get().getDeviceId();

9. 事件化计时器

trackTimerStart
初始化一个事件计时器,参数为计时事件的事件名称,返回值为该事件计时器唯一标识

trackTimerPause
暂停事件计时器,参数为trackTimerStart返回的唯一标识

trackTimerResume
恢复事件计时器,参数为trackTimerStart返回的唯一标识

trackTimerEnd
停止事件计时器,参数为trackTimerStart返回的唯一标识。调用该接口会自动触发删除定时器。

removeTimer
删除事件计时器,参数为 trackTimerStart 返回的唯一标识。
该接口会将标识为 timerId 的计时器置为空。调用停止计时器接口,会自动触发该接口。注意移除时不论计时器处于什么状态,都不会发送事件。

clearTrackTimer
清除所有已经注册的事件计时器。
存在所有计时器需要清除时调用。注意移除时不论计时器处于什么状态,都不会发送事件。

参数说明

参数参数类型说明
eventNameString事件名称,事件标识符
attributesMap<String, String>事件发生时所伴随的属性信息

返回值说明

参数参数类型说明
timerIdString计时器唯一标识

示例

String? timerId =await GrowingAutotracker.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();

10. 注册模块组件

registerComponent
可通过该方法手动注册SDK需要的可配置模块组件(推荐在初始化通过 Configuration 初始化时注册)。

参数说明

参数参数类型说明
moduleLibraryGioModule模块
configConfiguration模块的配置类(可选参数)

示例

GrowingAutotracker.get().registerComponent(ProtobufLibraryModule());

11. 发送无埋点页面事件

trackCustomPage
可以手动将一个 Widget 作为 Page 页面,发送一个 Page 事件。

参数说明

参数参数类型说明
titleString页面标题
widgetWidget控件

示例

class SplashScreen extends StatefulWidget{

SplashScreen({Key? key}) : super(key: key){
GrowingAutotracker.get().trackCustomPage("Splash页面", this);
}
}

12. 自定义无埋点页面事件属性

IGrowingPage
使用 IGrowingPage 接口,可以自定义页面事件的标题,路径和事件属性。页面事件会优先使用该接口里面赋予的值

参数说明

参数参数类型说明
pageTitleString页面标题
pageUriString页面Uri
pagePathString页面路径
attributesMap页面属性

示例

class SplashScreen extends StatefulWidget with IGrowingPage{

/// 页面标题

String? get pageTitle => "Splash页面";

///格式为:package::aaa/bbb.dart/PageWidget
///其中前缀为 为 dart 的 importUri,后缀为页面的 Widget。

String? get pageUri => "package::ui/splash.dart/SplashScreen";

///如 /books/100

String? get pagePath => "/splash";

///页面属性

Map<String, String>? get attributes => {"action":"欢迎"};

}